Night Owl 6

home *** CD-ROM | disk | FTP | other *** search

/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 034a / qread20.zip / QREADER.DOC < prev next >

Wrap

Text File | 1992-01-24 | 76KB | 1,737 lines

------------------------------------------------------------------ | | | | | | | | | QReader Version 2.0 | | | | The `Full-Screen' On-line Text Door | | | | | | For | | | | PCBoard Version 14.5x | | | | Wildcat! Version 3.0x | | | | and any BBS using the DOOR.SYS door file. | | | | Powerful On-Line text reading with the ability to scroll | | through text files using PgDn, PgUp, DownArrow, UpArrow, | | Home(top) and End(bottom). | | | | Slides screen with Left and Right arrow keys for text | | which is over 80 characters wide. | | | | Full featured Find / Repeat-find commands will display | | found text highlighted in the center of the screen, with | | the rest of the screen filled with the lines of text | | that come before and after the found text. | | | | Completely DESQview aware. | | | | Supports non-standard COM ports. | | | | | | All Options Are Sysop-Configurable | | | | | | | | | | QReader (C) Copyright 1991-1992 Yandell Computer Services | | | | 12121 Little Road - Bldg. 303 - Suite 212 | | Hudson, FL 34667 | | | | DATA -- (813) 842-8099 (HST) | | | | | | January 24, 1992 | | | | | | | ------------------------------------------------------------------ -------------------------------------------------------------------- QReader -------------------------------------------------------------------- TABLE OF CONTENTS Page ----------------- ---- INTRODUCTION ------------ 1.0 What is QReader 3 1.1 QReader's History and What's New 3 PRELIMINARIES ------------- 2.0 A Word on Installing QReader 4 2.1 Install the SAMPLE First 4 2.2 Installing Editors In QRSETUP.DEF 4 INSTALLATION ------------ 3.0 Installing Text Into a QReader Configuration 5-13 3.1 Installing Configurations Into Select Mode 14 3.2 Starting QReader in Select Mode 14 3.3 Setting Up Door Files to Call QReader 15 3.4 Setting Up Menus. Helps, Etc. 16 3.5 Color and Information Macros 17 3.6 Setting Up PROTOCOL.DAT 18 3.7 Setting Up SEND.BAT 19 3.8 Setting Up QReader for Non-Standard COM Ports 20 3.9 Memory Considerations and SWAP 20 3.10 Editing Full-Screen Reader Help Window Contents 20 RUNNING QReader --------------- 4.0 Notes on the Full Screen Reader 21 4.1 Running QReader Locally 21 4.2 Notes on Downloading In QReader 22 4.3 Differences in `generic' DOOR.SYS mode 22 4.4 On-Line Sysop Functions 23 4.5 Multi-nodes, Networks, Multi-taskers 24 MISCELLANEOUS ------------- 5.0 Where to Receive Assistance 24 5.1 Log Entries 24 5.2 Technical Notes 25 5.3 Error Messages 25 5.4 Disclaimer and Warranty 26 5.5 About the Author 26 5.6 Acknowledgments 26 REGISTRATION ------------ 6.0 Registering QReader 27 -------------------------------------------------------------------- Page 3 QReader Page 3 -------------------------------------------------------------------- 1.0 What is QReader -------------------- QReader is an on-line text reading door with many powerful features. Callers may scroll through the text as they read it with cursor keys, such as the PgDn, PgUp, UpArrow, and DownArrow. The Home key will return the caller to the top of the file, and the End key will place them at the bottom of the file. For those systems which may have text which is longer than 80 characters per line (typically business' with 132 column reports) QReader will even slide the text left and right with the left and right arrow keys! QReader has a full-featured (F)ind text facility, complete with a (R)epeat find command. Found text is displayed in the center of the screen. If the caller is in color, the found text is highlighted, otherwise it is underlined. When text is found, a full screen is presented to the caller and the lines of text before and after the found text are displayed around the line of found text. The (R)epeat find command works in the same fashion. The (Z)ippy text search command at the main menu provides extremely fast text searches in text files. After the caller selects the text to search for, they may select which of the text items to search, or they may choose to search (A)ll of the items in a configuration. QReader displays both DOS and non-DOS (Unix, Amiga, etc) text files. Callers may download from QReader. QReader has a unique downloading facility, specially designed for systems who wish to carry back issues of daily, weekly, and monthly news items. If desired, QReader will automatically create the directory the caller sees on the fly, based on the physical presence of the files. No need to manually update directory files! Plus it looks like a regular directory! QReader comes with an installation program which is second to none. F1 help is available at each installation parameter. The Sysop may configure their own Text, Color Macro, and ANSI editors to use from *WITHIN* QRSETUP. 1.1 QReader's History and What's New ------------------------------------- Please refer to the enclosed FEATURES.NEW file for a listing of new features in QReader version 2.0. If you already have QReader version 1.0 installed, you MUST follow the steps outlined in UPGRADE.DOC *BEFORE* attempting to run QReader version 2.0. -------------------------------------------------------------------- Page 4 QReader Page 4 -------------------------------------------------------------------- 2.0 A Word on Installing QReader --------------------------------- The purpose of this documentation is to explain to you how to install the QReader program. It assumes you are already familiar with basic door installation in your BBS software's environment. QReader is NOT an "instant-install" door. If you are reading this on the screen and have not yet printed out this documentation, please do so now. It will make things much easier for you. 2.1 Install the SAMPLE First ----------------------------- Enclosed with QREAD20.ZIP is a small sample configuration which is ready to run. To install this sample configuration, extract the entire contents of QREAD20.ZIP to a directory called \QREADER. Next, create a subdirectory called \QREADER\SAMPLE. Extract the contents of SAMPLE.ZIP (enclosed in QREAD20.ZIP) into \QREADER\SAMPLE. Next, run the QRSETUP program. Select option #1, to create or modify configuration files. Select (E)dit. You will be shown a window of all .CNF files. Highlight SAMPLE.CNF and press enter. Change the DRIVE letter in each parameter to the drive you created the \QREADER and \QREADER\SAMPLE directories on. Save the configuration file. This is all that is needed to see QReader in action with the SAMPLE configuration. At the initial QRSETUP screen, select "Run QReader in local testing mode". Select the SAMPLE.CNF file again. Answer the "Start in color?" question, and QReader will start. If you wish to run this SAMPLE configuration remotely, jump ahead to page 15 section 3.3 regarding QReader door batch files. Review the SAMPLE Qreader configuration. You should become familiar with the layout and "feel" of this configuration. It will be of great assistance when installing your own text into QReader. 2.2 Installing Editors In QRSETUP.DEF -------------------------------------- Before proceeding with the installation, you need to define the external file editors that YOU will use while installing or modifying a QReader configuration. At each installation parameter which deals with a text file (MENU, HELLO, etc.) you may create or edit that text file from within the QRSETUP program. These external editors are defined in QRSETUP.DEF. The enclosed QRSETUP.DEF file contains instructions on how to modify this file. Simply load QRSETUP.DEF into a text editor, and follow those instructions. -------------------------------------------------------------------- Page 5 QReader Page 5 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration ------------------------------------------------- QReader has been designed so that unlimited publications, tutorials, or text of any kind may each be installed as a door. All QReader doors may be run from one directory (\QREADER) by using different door configuration files. Keep this in mind as you install QReader. Run QRSETUP. Select #1 (Create and/or modify config file). A window of available .CNF files is displayed if (E)dit is chosen. You will most likely want to (C)reate a new file at this point. PROMPT> Config file to create: _ The config file name should indicate the publication or type of text in this installation of QReader (INFOMAT.CNF, BIX.CNF, NEWSBYT.CNF, TUTORIAL.CNF, etc.). You MUST use the .CNF extension on all QReader configuration files! The recommended setup for all QReader areas is to create the main \QREADER directory, and for each type of text item you will be installing, create a subdirectory off of the \QREADER main for that particular text (publication, etc.) Each configuration parameter is described on the following pages. F1 help is available at all QRSETUP configuration parameters. Name of this system ------------------- The name entered here is displayed at the program's termination in the "Registered To:" message (registered copies only). The name indicated in this parameter MUST be the exactly the same as the name used when registering QReader, and must be entered exactly the same into all .CNF configuration files. QReader registration number --------------------------- This is the number received when QReader has been registered. Registration will replace the "Unregistered Copy" message (which appears at program termination) with the name of your system. Registration will entirely remove the "Unregistered Copy" message which appears after the HELLO screen appears. Registration will remove the brief delays that are encountered with the above "Unregistered Copy" messages. You may receive a registration number INSTANTLY by ordering with a major credit card! See the enclosed file ORDER.FRM for details. Section 3.0 continues on the next page -------------------------------------------------------------------- Page 6 QReader Page 6 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- Loc\Name of Welcome file ------------------------ This is the file displayed to the caller when first entering QReader or after selecting this area from another area with (S)elect (see page 14 section 3.1). Please see page 16 section 3.4 for details on QReader's text file use. A file named HELLO may contain color macros thereby serving as the same file for both color and non-color use. If you wish, you may use an ANSI file for the color version by adding a "G" to the end of the filename when creating the file (but do not add the "G" in THIS parameter!). It is recommended this file contain some introductory information about the text contained in this configuration of QReader. You may specify unique welcome files for different QReader configurations by specifying different file names and\or locations in this parameter. The easiest way to implement different welcome files among multiple QReader configurations is to name all of the welcome files HELLO, and keep each HELLO in each configurations own subdirectory off of the \QREADER main directory (with the individual text files). Use of information macros in this file, especially the @FILEDATE@ macro, is highly recommended. The @FILEDATE@ macro is replaced with the NEWEST file date from the list of text files contained in this QReader configuration. The @FILEDATE@ macro provides an automated way for the caller to be notified of the last date the text they are reading was updated. When (S)electing a QReader configuration from another, this file will NOT be displayed when the new configuration loads if the files in this parameter of both .CNF files are the same LOCATION AND NAME. Refer to page 17, section 3.5 for additional @macro@ information. This file is optional. Leave this parameter blank if it is not used. Loc\Name of Menu file --------------------- Please see page 16 section 3.4 for details on QReader's text file use. A file named MENU may contain color macros, thereby serving as the same file for both color and non-color versions. If desired, you may use an ANSI file for the color version by adding a "G" to the end of the filename when creating the file (but do not add the "G" in THIS parameter!). You may use unique MENU files for different QReader configurations by specifying different file names and\or locations, however this is not usually necessary. Refer to page 17, section 3.5 for additional @macro@ information. Section 3.0 continues on the next page -------------------------------------------------------------------- Page 7 QReader Page 7 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- Loc\Name of Help file --------------------- The HELP file included with QReader is a "multi-paged" PCBoard macro style file. Please see page 16 section 3.4 for details on QReader's text file use. A file named HELP may contain color macros, thereby serving as the same file for both color and non-color versions. If desired, you may use an ANSI file for the color version by adding a "G" to the end of the filename when creating the file (but do not add the "G" in THIS parameter!). You may use unique HELP files for different QReader configurations by specifying different file names and\or locations, however this is not usually necessary nor is it recommended. Level to Select this text ------------------------- This is the security level a caller will need to (S)elect this configuration of QReader from a different QReader configuration. For example, you offer 5 text areas (5 different QReader .CNF areas) on-line. You want all callers to be able to enter QReader, but you only want callers at a certain level (or above) to be able to access two of the five publications. Install all five publications into QReader's SELECT mode. If this configuration (the one being edited now) is one which only certain callers should access, enter their security level here. This parameter is only valid if this configuration of QReader has been installed as part of QReader's SELECT mode. Please refer to page 14 for more information regarding QReader's SELECT mode. Level to use Select command --------------------------- This is the security level a caller will need to enter the (S)elect command at the Main prompt in QReader. This parameter should not be confused with the "Level to Select this text" parameter (The parameter preceding this one in QRSETUP). Section 3.0 continues on the next page -------------------------------------------------------------------- Page 8 QReader Page 8 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- Loc\Name of text menu --------------------- This is a menu displayed to the caller when (R)ead is selected. It shows text selections which are available for this configuration. For example, if this configuration is an area which contains 18 individual text files, the file indicated in this parameter will need to describe each of the 18 items for the caller. Each text item (description) in this file must be numbered, so that when the caller selects a number from this menu, they will be shown the corresponding file for that number (see the "Loc\Name of text data file" parameter on the next page). Please see page 16 section 3.4 for details on Qreader's text file use. This file may contain color macros, thereby serving as the same file for both color and non-color versions. If desired, you may use an ANSI file for the color version by adding a "G" to the end of the filename when creating the file (but do not add the "G" in this parameter!). You MUST specify unique files in this parameter for other QReader configurations by specifying different file names and\or locations. The recommended location of this file is in the subdirectory off of the \QREADER main for this configuration, where the individual text files for this configuration reside. It is completely up to the Sysop to decide on a filename for this file. The file specified in this parameter should not, however, contain an extension. It is recommended that the filename chosen for this parameter should give some indicator of which QReader configuration it belongs to. For instance, in our SAMPLE.CNF configuration we call this file SAMPLE. Section 3.0 continues on the next page -------------------------------------------------------------------- Page 9 QReader Page 9 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- Loc\Name of text data file -------------------------- This is the data file which contains the names of each individual text file (for reading) which make up this QReader configuration. You should assign this file an extension of .DAT in all of your QReader configurations. PRESS F2 to create and edit this file. For example: Text File Name Description of File Contents Notes ------------------- -------------------------------- ----- NEWS1.TXT Weather NEWS2.TXT News NEWS3.TXT Sports NEWS4.TXT Misc. The text data (.DAT) files may contain two additional fields for each text item. The "Description of File Contents Field" is a short description of the particular text item. This is displayed when doing a Zippy scan on several items, for instance if USA Today is being searched: Searching Item (1) Advertising Searching Item (2) Banking and Economy Searching Item (3) Bonus Section etc... The "Notes" field is a very short field which is only used by the Sysop to place a small notation about a particular item. It is never displayed anywhere other than here in the QRSETUP .DAT file editor. If desired, the "Location of text files" parameter (below) may be over-ridden by placing a path along with a filename in the above "Name..." parameter. While it is recommended that all files in a particular configuration all be located in the location specified for them in QRSETUP, this ability allows more flexibility if needed. If a file in a .DAT file contains a path, the "Location of text files" parameter will not be used for THAT particular file. The file in the "Text Menu File" parameter (the parameter preceding this one) should indicate that selecting #1 would show the caller the contents of NEWS1.TXT, #2 would display NEWS2.TXT, etc. It is recommended that each configuration's .DAT file reside in the configuration's own subdirectory off of the \QREADER main directory. Up to 500 text files may be installed in each text data (.DAT) file. Section 3.0 continues on the next page -------------------------------------------------------------------- Page 10 QReader Page 10 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- Loc\Name of QReader log ----------------------- If desired, QReader will keep a separate log file of the selections callers are reading and downloading. Enter a location and filename in this parameter if this is desired, otherwise leave this blank or enter NONE. Location of text files ---------------------- Enter the location where the text files for reading are located. This will be the location where the files listed in the data (.DAT) file are located. Enter the location ONLY, not a file name! Prompt ------ You may customize the QReader main menu prompt. Any valid QReader text @macro@ macros may be used (see page 17 section 3.5). Color macros cannot be used in the prompt at this time. Description ----------- The `Desc:' parameter is the `TOP' information line of the QReader `Full Screen Reader'. This stays at the top of the screen while the `Full Screen Reader' is active. This line should provide information about the text contained in this configuration of QReader. If this configuration of QReader is a news based item updated daily, weekly, or monthly, this is an ideal place for the @FILEDATE@ macro. QReader automatically detects the LATEST file date of the text files installed for reading, and anywhere the @FILEDATE@ macro is used it is replaced with this date. Reader status line ------------------ You may customize the status line in the `Full Screen Reader'. This is the next to the last line on the screen and stays there while the 'Full Screen Reader' is active. While you may change this parameter to your liking, it is recommended that it contain (H)elp information for the 'Full Screen Reader' pop-up help window. Valid help keys are (H)elp, F1 (doorway mode) or ?. Section 3.0 continues on the next page -------------------------------------------------------------------- Page 11 QReader Page 11 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- The second page of options in QRSETUP starts below: --------------------------------------------------- Location of download files -------------------------- If downloads are allowed in this configuration of QReader, the files available for downloading must be located in the location specified in this parameter. Do NOT enter a file NAME here, just the location. Mask for Auto-Dir filenames --------------------------- Auto-Dir is the process where QReader creates a DIR `on the fly' to display to the caller. This is very handy if you wish to offer back- issues of text publications for download. Simply place a `mask' for finding file names in the `Location of Download Files' parameter and QReader will display `matches' in the familiar BBS DIR format. For example, if you are carrying the weekly `Modem Times' on-line, and the ZIPped issues are named MDMT0120.ZIP, MDMT0127.ZIP, etc., place MDMT*.ZIP in this parameter. If you only wish a single file to be downloaded, enter the entire file name in this parameter. Also see the other `Auto-Dir' parameters for more Auto-Dir features. Enter NONE in this parameter if you do not wish to use Auto-Dir. Sort method for Auto-Dir ------------------------ If using the `Auto-Dir' method for displaying downloadable files to the caller you may specify the method in which they are sorted prior to being displayed. If `Auto-Dir' is being used to display daily, weekly, or monthly publications, the sort method would usually be 1. This means the newest file is displayed first. Valid Sort options are: 1) Date descending, Newest file displays first, oldest will be last. 2) Date ascending, Oldest file displays first, newest will be last. 3) Alphabetically, From A-Z. 4) None - No sort, Files are displayed in the order found on drive. Also see the other `Auto-Dir' parameters for more Auto-Dir features. Section 3.0 continues on the next page -------------------------------------------------------------------- Page 12 QReader Page 12 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- Auto-Dir description -------------------- Downloadable files which are displayed using Auto-Dir should have a brief 30 character description which is displayed with each of the Auto-Dir files. The following is a typical Auto-Dir listing: MDMT0127.ZIP 84231 01-27-92 Issue of Modem Times (Time: 0.4 min) MDMT0120.ZIP 78617 01-20-92 Issue of Modem Times (Time: 0.3 min) MDMT0113.ZIP 82452 01-13-92 Issue of Modem Times (Time: 0.4 min) The `Issue of Modem Times' is the brief description you would enter in this parameter. The download time (in parenthesis) is added by QReader automatically after this description. Enter NONE in this parameter if you do not wish to use Auto-Dir. Loc\Name of DIR file -------------------- This parameter has two uses: 1) It can be used as a `header file' for Auto-Dir. It will be shown just before the Auto-Dir is displayed. This DIR file may contain additional information about the download files in the Auto-Dir. - OR - 2) If you do not wish to use `Auto-Dir', make this a regular BBS DIR file with names and descriptions. Be sure to enter NONE for all other Auto-Dir parameters. Enter NONE if you do not wish to use this feature or if downloading is disabled in this QReader configuration. Security to (D)ownload ---------------------- This is the security level a caller needs to (D)ownload in QReader. If the caller's security level is equal to or higher then the level specified in this parameter, the caller will be able to use the (D) key and download. Section 3.0 continues on the next page -------------------------------------------------------------------- Page 13 QReader Page 13 -------------------------------------------------------------------- 3.0 Installing text into a QReader configuration (continued) ------------------------------------------------------------- Free Download Status -------------------- You may select how (and if) callers are charged for downloads. This setting is only valid when QReader is being used in the PCBoard or Wildcat mode. It is ignored in the "generic DOOR.SYS" mode. (0) Regular download - Count, bytes, and time are charged. (1) Free download - Time is charged, Count and bytes are not (2) Free / No time - Count, bytes, and time are not charged. (3) No time download - Time is not charged (clock stops), count and bytes are charged. Disable (G)oodbye Command ------------------------- If you do not wish callers to logoff from inside QReader, answer Yes to disable the (G)oodbye command. If (G)oodbye is disabled it should be removed from all MENU and HELP files. This setting is only valid when Qreader is running in the PCBoard or Wildcat modes. It is ignored if QReader is running the "generic DOOR.SYS" mode, since (G)oodbye is never available in that mode. Swap QReader when Shelling -------------------------- QReader has the ability to SWAP itself out of memory to EMS or disk when shelling (DSZ\GSZ downloads, F5 or ALT-D Sysop drop to DOS). Answer N to disable swapping. Answer D to force QReader to swap itself to Disk during a shell. Answer Y to allow QReader to test if EMS is present, and swap itself to EMS if so. If EMS is not found, QReader will swap itself to disk. Never use swapping if QReader is running in a multi-tasking environ- ment other than those listed as supported in this manual. Start with Full-Screen Mode Off ------------------------------- Under certain circumstances, it may be desirable for QReader to use the NON-Full-Screen mode for displaying files. This toggle forces QReader to behave as if the NON-Full-Screen reader was the default, instead of the opposite. This capability is not normally required, therefore this parameter should normally be answered N for no. BBS Software Being Used ----------------------- (1) PCBoard version 14.5x ONLY. (2) Wildcat version V3.0x ONLY. (3) Other systems that create a generic DOOR.SYS file. -------------------------------------------------------------------- Page 14 QReader Page 14 -------------------------------------------------------------------- 3.1 Installing Configurations Into Select Mode ----------------------------------------------- The main menu (S)elect command allows callers to load in another QReader door configuration without exiting QReader. If you have more than one QReader configuration and wish them to be "Selectable" from each other, you will need to modify two files for this purpose: SELECT - this is a menu file which describes other text which can be selected by the caller. SELECT.DAT - this is an ascii file which contains the name of each QReader configuration (.CNF) file on each line. The line "number" each configuration file is on must correspond to the number designated to select this text in the SELECT menu file. In other words, if selection #4 in the SELECT menu is supposed to load USA- Today, then the 4th line of SELECT.DAT should be a USA.CNF file. It is recommended you place different welcome files in each .CNF file when using the Select option. If the welcome file is the same name and location in the newly loaded .CNF file as the previous one, it will NOT be displayed (again) to the caller. If you do not wish to allow callers to call up other QReader door configurations in this manner simply delete or rename SELECT.DAT. You may nest additional categories in the SELECT.DAT file, for instance, instead of (or along with) .CNF files in SELECT.DAT, you may place files such as SELECT1.DAT, SELECT-A.DAT, etc. (you name them, as long as they have a .DAT extension and reside in the QReader main directory). Using the above example, you would need a SELECT1 and SELECT-A (no extension) menu selection file for the corresponding SELECT??.DAT files. Using this method, you may nest categories from the original SELECT.DAT file as deeply as needed. 3.2 Starting QReader in Select Mode ------------------------------------ QReader has the ability to start in a "Select" mode. This mode is typically used when you carry several different publications on-line and only want to install one door (a LIBRARY, for example). You MUST configure the files explained in section 3.1 above before proceeding. To start QReader in a SELECT mode, simply use SELECT.CNF as the configuration file. Whenever SELECT.CNF is used, QReader will go to the SELECT menu first, allowing the caller to make selections from SELECT.DAT. For instance, instead of three separate doors for BIX, NewsBytes, and Infomat, you may have one QReader door which starts in the select mode. A different configuration screen appears when editing SELECT.CNF in QRSETUP. This is because of the minimal info needed to bring QReader up in the Select mode. The parameters are self explanatory. -------------------------------------------------------------------- Page 15 QReader Page 15 -------------------------------------------------------------------- 3.3 Setting Up Door Files to Call QReader ------------------------------------------ The purpose of this section is to describe the command line calling parameters for QReader in a door (batch) file. You must refer to your BBS manual for complete instructions on installing doors. When installing any QReader door into PCBoard using PCBSETUP to edit your DOORS.LST file, you MUST answer YES to use a USERS.SYS file! Door batch calling syntax is: QREADER CONFIG-FILE SYSTEM-DIR qreader sample.cnf c:\pcb\ EXAMPLE PCBoard door batch file: @echo off cd\qreader QREADER.EXE QREADER.CNF C:\PCB cd\pcb | | board.bat | --- Location where node's PCBOARD.SYS, | | USERS.SYS, and PCBOARD.DAT will be | | located (No name, just a location!). | | | - Config file name | - Omit the call to BOARD.BAT if SHELLING to doors. EXAMPLE Wildcat door batch file: @echo off cd\qreader QREADER.EXE QREADER.CNF C:\WC30\WCWORK\NODE1 cd\wc30 | | cat.bat | --- Location where node's DOOR.SYS and | | USERINFO.DAT will be located. | | (No name, just a location!). | | | - Config file name | - Omit the call to CAT.BAT if SHELLING to doors. NOTE: When setting up your BBS configuration for QReader doors, you should only SHELL to QReader if you can SWAP your BBS out of memory at the same time. Otherwise, you should set up your BBS to "exit" to QReader and then allow the BBS door files to bring the BBS back up by ending with the BBS batch file as shown above. -------------------------------------------------------------------- Page 16 QReader Page 16 -------------------------------------------------------------------- 3.4 Setting Up Menus, Helps, Etc. ---------------------------------- This section deals with the text display files QReader uses. These files are MENU, HELLO, HELPx, SELECT, and any text menus you create. The files which come with QReader utilize the PCBoard color macro method instead of ANSI. This allows one file to be used instead of two files. QReader allows three different file types to accommodate different BBS systems. The examples below illustrate the MENU file but apply to all of the files listed above: Type #1 - PCBoard color macros. Using PCBoard color macros, both color & non-color versions of the file are in one file called MENU. Type #2 - Wildcat color macros. Using Wildcat color macros, both color & non-color versions of the file are in one file called MENU. Type #3 - Ascii and ANSI files. The non-color file is a regular Ascii text file called MENU. The color file is an ANSI file that is called MENUG. When ANSI is used in any of the above files, the "G" must be added to the file name. If you wish to modify the enclosed text files using a different method, use the QR-CONV.EXE program to convert the enclosed type #1 files to type #2 or type #3. QR-CONV.EXE will only convert the unedited text files enclosed in QREAD20.ZIP. Important: When modifying ANSI files, TheDraw is recommended. When saving the file, if you wish the screen to clear you will need to select that option. When asked for the "Line Length" by TheDraw when saving a file, always answer NONE for best performance in QReader. Previously, some Sysops experienced difficulty when editing the multi-paged text files such as HELP. QReader now supports linking files together, by specifying a "next" filename in the file currently being displayed. This is done by placing a % (percent) in the LEFT-MOST (column #1) position on line #24 of the current file. The % must then IMMEDIATELY be followed by the file QReader is to display next, such as %HELP2. This allows the Sysop to edit each page easily and separately, especially those wishing to use the ANSI file method. It is recommended the %FILENAME be located on the 24th line of each file where it is being used, so the new file will begin immediately after a "More?" prompt appears. IMPORTANT: Regardless of the file type in use, do not designate the %FILENAME parameter while using a color ANSI or macro editor. These editors will place color instructions BEFORE the % on the line, thereby removing the % from the first position in the line. The %FILENAME must be added with a plain text editor AFTER saving the file with the color editor. Refer to the enclosed HELP? files for examples of linking these long files together by making individual shorter files. Refer to page 17 section 3.5 for the macro chart. -------------------------------------------------------------------- Page 17 QReader Page 17 -------------------------------------------------------------------- 3.5 Color and Information Macros --------------------------------- QReader utilizes the color macro convention used in PCBoard 14.5x and Wildcat 3.0x. The color chart is enclosed below for other BBS system Sysops who wish to use color macros instead of ANSI. Background (first digit) Foreground (second digit) ----------------------- ------------------------- Black = 0 Black = 0 Blue = 1 Blue = 1 Green = 2 Green = 2 Cyan = 3 Cyan = 3 Red = 4 Red = 4 Magenta = 5 Magenta = 5 Yellow = 6 Yellow = 6 White = 7 White = 7 Background(Blinking Foreground) High Intensity(Bright Foreground) ------------------------------- --------------------------------- Black = 8 Black = 8 Blue = 9 Blue = 9 Green = A Green = A Cyan = B Cyan = B Red = C Red = C Magenta = D Magenta = D Yellow = E Yellow = E White = F White = F Examples: Bright White on Black background: @X0F (PCB) or @0F@ (WC) Bright Yellow on Red background : @X4E (PCB) or @4E@ (WC) Blinking Bright Red on Black : @X8C (PCB) or @8C@ (WC) Information macros allowed (in any text file) @CLS@ clear screen @FIRST@ is the callers first name, (cased, i.e. Brent). @SYSDATE@ is the current date. @DATE@ is also the current date. @SYSTIME@ is the current time. @TIME@ is also the current time. @TIMELEFT@ is the minutes left for the caller. @LEFT@ is also the minutes left for the caller. @FILEDATE@ is the newest date found for the text files installed in the current configuration's text data (.DAT) file. @FILETIME@ same as @FILEDATE@, except it uses newest time. @QRSTATUS@ will display ON or OFF for the status of the Full Screen Reader. ON has one space padded at the end, to make it the same length as OFF. @FILEDATE1@ \ Up to 500. If using a text type where an entire issue @FILEDATE2@ >is in a single file, and there is more than one issue @FILEDATE3@ / in a single configuration, this will retrieve the file date of EACH file in the list of files for display. -------------------------------------------------------------------- Page 18 QReader Page 18 -------------------------------------------------------------------- 3.6 Setting Up PROTOCOL.DAT ---------------------------- If you allow downloading, you may wish to review the enclosed PROTOCOL.DAT file to see if it meets your needs. PROTOCOL.DAT is used to configure the designated "letter" for each type of protocol. QReader contains no internal protocols and relies solely on external protocols such as DSZ for this function. Sample PROTOCOL.DAT ------------------- X,N,Xmodem,T C,N,Xmodem/CRC,T O,N,1K-Xmodem,T F,Y,1K-Xmodem/G,T Y,N,Ymodem,T G,Y,Ymodem-G,T Z,N,Zmodem,T There are 4 parameters on each line, each separated by a comma: Parameter #1 - the protocol letter choice. Parameter #2 - Y if error correction is required for this protocol, N or blank if not. Parameter #3 - short protocol description. Parameter #4 - B will force the QReader status line to appear at the bottom of the screen, a T or blank will make the QReader status line appear at the top of the screen during the protocol shell. Parameter #4 recommendations: For DSZ protocols use T (top). For GSZ protocols use B (bottom). Place SET GSZWINDOW=21 in each node's batch file which starts the BBS. For HS-Link use T (top). Example line in PROTOCOL.DAT (using DSZ): Z,N,Zmodem,T (using GSZ): Z,N,Zmodem,B Others: Use what works (looks) best for you. You may use any letter as a protocol except "V". The caller will have the opportunity at the protocol prompt to view the contents of any ZIP file by selecting View. The ZIP view is internal to QReader. See the next section about setting up SEND.BAT. See page 22 section 4.2 for additional details about downloading. -------------------------------------------------------------------- Page 19 QReader Page 19 -------------------------------------------------------------------- 3.7 Setting Up SEND.BAT ------------------------ QReader uses a single batch file for all external protocols. It is not within the scope of this manual to provide instructions for setting up different types of protocols and all of their individual command line options. The enclosed SEND.BAT and PROTOCOL.DAT, along with the popular DSZ external protocol should provide ample protocol coverage for the simple task of downloading files from QReader. If you wish to add or delete protocols, the following information might assist you. SEND.BAT is passed the following parameters from QReader: %1 (speed) %2 (port) %3 (filename) %4 (protocol letter used in QReader) %5 base address (hex) for com port (use with portx option). %6 IRQ for com port (use with portx option). An examination of SEND.BAT will demonstrate how the protocol letter is used to branch to the appropriate protocol command. If you are familiar with this type of batch file programming you may wish to modify it. If not, our best recommendation is to use it "as is". As mentioned previously the default configuration used with the popular DSZ protocol will provide ample coverage. IMPORTANT: If using GSZ (the graphical counterpart to DSZ) for any of the protocols, place the following SET command in the batch file used to start the BBS on each node: SET GSZWINDOW=21 Sysops using non-standard com ports may use one SEND.BAT for all nodes without the need for DSZPORT environment variables, etc. On non-standard nodes QReader will pass the base address and IRQ as defined for the com port (See the next section 3.8 for non-standard com port installation). On standard nodes QReader will always pass 3f8,4 for COM1 and 2f8,3 for COM2. Example DSZ command line in SEND.BAT for non-standard COM ports: :Zmodem DSZ portx %5,%6 pB4096 sz -m %3 | (note comma) NOTE: The above paragraph applies only to those Sysops using COM ports other than 1 and 2 on their systems. See page 22 section 4.2 for additional details about downloading. -------------------------------------------------------------------- Page 20 QReader Page 20 -------------------------------------------------------------------- 3.8 Setting Up QReader for Non-Standard COM Ports -------------------------------------------------- If running QReader in the PCBoard mode, non-standard COM ports are handled automatically by QReader, which will obtain the information from each node's PCBOARD.DAT file. If running QReader in the Wildcat or generic DOOR.SYS mode: On the node which is actually using a com port other than 1 or 2, two environment variables must be set. These are QRBASE which is the base address in hex, and QRIRQ, which is the actual IRQ number. These can be set any time before QReader loads. It is recommended to set them in the node's AUTOEXEC.BAT file or the batch file that starts the BBS software. Example: SET QRBASE=3E8 SET QRIRQ=5 3.9 Memory Considerations and SWAP ----------------------------------- QReader shells on two occasions. One is when a caller downloads from QReader, and QReader calls upon the external protocol. Another is when F5 or ALT-D is pressed on the host for local drop to DOS. If you want QReader to SWAP itself to EMS or disk, you must implicitly tell QReader to do so with the appropriate parameter in the QRSETUP program in each .CNF configuration file. If swapping has been enabled, QReader will SWAP itself out of memory and into EMS memory. If there is no EMS memory, QReader will SWAP itself to a disk file. This leaves a small 5K QReader program in memory, which re-loads the EMS or disk file when QReader is returned to from the shell. If QReader has swapped itself to disk, the files created are called QRSWPxxx.$$$ where the "xxx" is the node number. 3.10 Editing Full-Screen Reader Help Window Contents ----------------------------------------------------- This is text which appears in the Pop-Up help window found in the Full-Screen reader. To edit the contents of this help window, run QRSETUP and select option #3 from the main screen (Create and/or modify QRFSHELP.* files). If running QReader with PCBoard software, you may use language extensions on QRFSHELP files. The appropriate file will be used if a caller is using a language, and if the appropriate QRFSHELP file exists. The ability to customize the text in the Pop-Up help window, along with the ability to customize important command prompts and status lines, makes QReader well suited for multi-language use. -------------------------------------------------------------------- Page 21 QReader Page 21 -------------------------------------------------------------------- 4.0 Notes On The Full Screen Reader ------------------------------------ QReader's full screen reader requires the caller's terminal to be ANSI capable. This is so screen positioning instructions can be sent to the caller. QReader NEVER changes the caller's screen color if the caller is in non-color mode. QReader loads the entire text file into memory when using the full screen reader. The full screen reader will NOT be used if any one of the following conditions exist: 1) The caller's terminal program is not ANSI capable. 2) The text file will not completely load into memory on the host. 3) The caller has manually turned the full screen reader off. 4) The text file contains ANSI escape sequences. 5) The caller is at 300 baud. If one of the above conditions exist, a "non-full screen reader" is used to display the file to the caller. QReader's non-full screen reader has text (F)ind features, (R)epeat finds, (T)op of file, etc. however they are not quite as enhanced as those found in QReader's `Full Screen Reader'. (F)ind type features are not available on ANSI files. 4.1 Running QReader Locally ---------------------------- The simplest and easiest way to run QReader locally is from the QRSETUP program. At the first screen, simply select the option for running QReader locally, then select the appropriate configuration file to run. You will then be asked whether you would like to begin with color mode on or off. These selections allow you to see how QReader will appear to a caller on-line. QReader also works through the BBS in local mode and behaves in the same fashion as if a caller were on-line. When running QReader in the local maintenance mode (through QRSETUP) the name which appears on the status line will be (Local) SYSOP and will default to a time limit of 90 minutes. In the unlikely event that there is not enough memory for QRSETUP to load QReader, you can "force" the local mode on QReader's command line. Simply enter QREADER CONFIG-FILE.CNF /L (or /LG for color). CONFIG-FILE.CNF would be the configuration file to use while in local mode. QReader supports PCBoard's /LOCALON network mode, if running QReader with PCBoard version 14.5a. This is handled automatically by PCBoard and QReader. -------------------------------------------------------------------- Page 22 QReader Page 22 -------------------------------------------------------------------- 4.2 Notes on Downloading In QReader ------------------------------------ You must use a DSZ log compatible protocol in conjunction with the DSZLOG= environment setting in order for QReader to determine if a download was successful or not. If you use the default SEND.BAT and PROTOCOL.DAT, QReader will expect to find DSZ in the current directory or DOS path. If the environment setting DSZLOG= is being used, QReader will correctly place successful/aborted download information in the QReader log file you have indicated for QReader's configuration. If running in PCBoard or Wildcat mode, QReader will write the download information to the caller (activity) log. If the PCBoard mode is being used, QReader will also write the download to PCBoard's DOWNLOAD.TXT file. If a caller does not have sufficient time remaining to download a file, the transfer will not be permitted. If running Qreader in the PCBoard or Wildcat mode, the Sysop has complete control over how the caller is charged for download counts and bytes, and whether the caller is charged for time it takes to download files. This is handled through the appropriate setting in the QRSETUP installation program. While QReader provides the ability to update PCBoard and Wildcat system files with caller download activity (counts and bytes), QReader does NOT attempt to test if a download will cause the caller to exceeded any "daily" byte or file counts. This would require QReader to read additional BBS system files for both software packages, and it is beyond the intended scope of what is intended to be a "simple" download mechanism in QReader. 4.3 Differences in `generic' DOOR.SYS mode ------------------------------------------- QReader contains a "generic" DOOR.SYS mode which will allow it to run in many BBS environments. This is what is used when QReader is being installed with a BBS system other than PCBoard or Wildcat. Some of these features cannot be enabled while running in the generic DOOR.SYS mode. * (G)oodbye cannot be used. The setting for the "Disable (G)oodbye command" is ignored. * All file transfers in "generic" DOOR.SYS mode are free. Download bytes, file counts, etc. are not updated in the BBS system files. * BBS caller (activity) log files are not updated. -------------------------------------------------------------------- Page 23 QReader Page 23 -------------------------------------------------------------------- 4.4 On-line Sysop Functions ---------------------------- The following function keys may be used by the Sysop while a caller is on-line. To see these keys defined, enter ALT-H and they will be displayed in a portion of the status line. F3 - (PCBoard mode only) Toggles the printer on or off. QReader follows this toggle from PCBoard and prints information such as text reading activity, downloads, carrier drops, and keyboard time-outs. Toggling F3 on or off in QReader also sets this toggle in PCBoard upon returning from QReader. F4 - (PCBoard mode only) Toggles Operator page on or off. Toggling the F4 key on or off in QReader sets this toggle in PCBoard upon returning from QReader. F5 - Local Sysop Drop to DOS. F6 - If you have attached a security level to QReader's Download function and the caller does not have sufficient security to download, pressing F6 will allow the caller to download the file. F7 - Toggles the local alarm on or off. QReader will follow this toggle from the BBS software as written in the BBS software's door information file. In PCBoard mode, toggling F7 on or off in QReader also sets this toggle in PCBoard upon returning from QReader. F8 - Returns the caller immediately and without warning to the BBS. F9 - Toggles the display on or off. QReader will follow the display toggle from the BBS software as written in the BBS software's door information file. In PCBoard mode, toggling F9 on or off in QReader also sets this toggle in PCBoard upon returning from QReader. F10 - This key will begin an on line chat session. Press ESCape to end the chat and return the caller to QReader. ALT-D - Local Sysop Drop to DOS. ALT-N - Sets the "Sysop on Next" toggle in PCBoard. ALT-X - Sets the "Exit" toggle in PCBoard. ALT-B - Sends a beep to the caller. ALT-H - Will display above Sysop functions. F5 drop to DOS, ALT-D drop to DOS, F8 quit to BBS, and F10 Chat are not available while the Full Screen Reader is active. -------------------------------------------------------------------- Page 24 QReader Page 24 -------------------------------------------------------------------- 4.5 Multi-nodes, Networks, Multi-taskers ----------------------------------------- QReader has been developed in a networked environment . All multi- node features have been tested on our own multi-node PCBoard system. Two of QReader's primary beta test facilities are twenty node systems. QReader version 2.0's largest beta test facility was a 143 node system. QReader is DESQview aware. It is automatically detected, screen and keyboard I/O are "well behaved", and time slices are given back to other applications while QReader is idle at an input prompt. QRSETUP is also completely DESQview aware. 5.0 Where To Receive Assistance -------------------------------- Yandell Computer Services (YCS) provides the following technical assistance for QReader: 813-842-8099 The YCS Support System. Available to all BBS Sysops. INSTANT on-line credit card registration and support system for YCS Shareware. All nodes are 14400 (HST). On-line 7 days per week, 24 hours per day. 5.1 Log Entries ---------------- The following information is written to a configuration's QReader log (if used): Completed downloads Name of each text file read The following is written to the node's caller (activity) log in PCBoard and Wildcat modes: The same entries in QReader log files plus: Aborted downloads Carrier drops Keyboard time-outs File access errors (Path not found) (Invalid drive) (File not found) Operator page attempts Sysop chat active Sysop chat ended Additionally, successful downloads are also entered in the PCBoard DOWNLOAD.TXT file. -------------------------------------------------------------------- Page 25 QReader Page 25 -------------------------------------------------------------------- 5.2 Technical Notes -------------------- Carrier is monitored by QReader. Should a caller drop carrier while using QReader, they will be returned to the BBS, which will detect the "no carrier" status and cycle appropriately. QReader uses approximately 154K of memory, plus the size of any text files which have been loaded into the `Full Screen Reader'. QReader only accepts valid commands as input at input prompts. QReader will exit if there are excessive invalid commands repeatedly entered at the main QReader input prompt. * PCBoard Mode Technical Notes ------------------------------- QReader requires the use of USERS.SYS to function. QReader gets the caller's security level, daily bytes, and number of downloads from this file. QReader also gets some status line information such as the caller's city, last date on, and number of times on. None of this information is available in PCBOARD.SYS, and using USERS.SYS for this information means QReader NEVER reads from or writes to any PCBoard system files. * Wildcat Mode Technical Notes ------------------------------- For the purposes of updating caller download counts and bytes, QReader writes this information to the USERINFO.DAT door file designed for this purpose. QReader NEVER reads from or writes directly to any Wildcat system files. Only the DOOR.SYS file and the USERINFO.DAT file, created by Wildcat upon exiting to QReader, are used by QReader. 5.3 Error Messages ------------------- The only error messages which should ever be displayed by QReader are self-explanatory file access error messages (not found, invalid drive, invalid directory, etc.). * bad command or filename * This message will be echoed to the screen if DSZ (or the specified external protocol) could not be found during a download attempt. External protocols must reside in the directory with QReader or in a valid DOS path. -------------------------------------------------------------------- Page 26 QReader Page 26 -------------------------------------------------------------------- 5.4 Disclaimer and Warranty ---------------------------- QReader is a shareware product. QReader may be uploaded to BBS systems provided copyright notices are not removed and no changes are made to the program. There are no warranties, expressed or implied, for unregistered copies of QReader. Sysops who install QReader assume any and all liabilities for anything which may result as a consequence of running QReader. For registered copies of QReader, Yandell Computer Services warrants that QReader will perform as described in this documentation. In the event QReader does not perform as specified, then Yandell Computer Services will elect to either fix QReader, or refund the amount paid, if notified within 30 days of registration. Under no circumstances shall Yandell Computer Services or the author of QReader be liable for any loss of profit or any other damages, including but not limited to special, incidental, consequential, or other damages, arising out of the use or inability to use QReader. 5.5 About the Author --------------------- L. Brent Yandell has been involved in telecommunications for five years, and has been updating and supporting various door programs for over four years as of this writing. Most PCBoard Sysops will be familiar with PCBFV, the popular on-line file viewer/extractor used in the PCBoard F V (File View) process. Many Sysops are familiar with USBBSDOR, a door for displaying the popular national USBBS listing. USBBSDOR has been written, updated, and supported for almost 5 years! 5.6 Acknowledgments -------------------- Appreciation and many thanks are in order for the following people: * Roy Timberman (Sound Advice) for making his twenty node system available for testing QReader, and providing a distribution site for new releases: 816-436-4516 (HST) and 816-436-8029 (Hayes). * Jeff Sumberg for the serial library used in QReader. * Jim Brewer for overall project review. * Tim Yandell for proofing this documentation. * All of the QReader version 2.0 beta testers. -------------------------------------------------------------------- Page 27 QReader Page 27 -------------------------------------------------------------------- 6.0 Registering QReader ------------------------ QReader is not free software. QReader should be registered no later than 30 days after installation. Registration is $25.00 and may be paid by check, money order, VISA, Mastercard, or Discover. If registering with a credit card, you may receive a registration number INSTANTLY! Refer to the enclosed file ORDER.FRM for complete registration instructions.